Hello R Markdown!

Choose your output format!

Why R Markdown?

• It’s simple. Focus on writing, rather than debugging silly errors or where pictures should go
• It’s flexible. Markdown was created to simplify writing HTML, but thanks to pandoc, Markdown converts to many different formats!
• It’s dynamic. Find a critical error? Get a new dataset? Regenerate your report without copy/paste hell!
• Encourages transparency. Collaborators (including your future self) will thank you for integrating your analysis & report.
• Enables interactivity/reactivity. Allow your audience to explore the analysis (rather than passively read it).

First things first, what is Markdown?

• Markdown is a particular type of markup language.
• Markup languages are designed produce documents from plain text.
• Markdown is becoming a standard. Many websites will generate HTML from Markdown.

Who is using R Markdown, and for what?

• The R Markdown website is built with R Markdown.
• The new edition of the ggplot2 book uses it.
• R package vignettes
• Many great tutorials use R markdown with add-ons such as Rgitbook.
• People are blogging with it.

What is R Markdown?

• Straight from the R Markdown home page:

R Markdown is an authoring format that enables easy creation of dynamic documents, presentations, and reports from R. It combines the core syntax of markdown (an easy-to-write plain text format) with embedded R code chunks that are run so their output can be included in the final document. R Markdown documents are fully reproducible (they can be automatically regenerated whenever underlying R code or data changes).

Markdown doesn’t natively support…

• Stuff you’d find in formal publications:
  • Figure/table referencin
    • This is actually available in markdown for Word with some extra code, and works with pdfs
• Many, many appearance related things (image/figure alignment, coloring, font families, etc.)

There is hope…

• Markdown will work with HTML/LaTeX markup, but don’t expect it to convert between output formats.
• There are many efforts to extend Markdown (but, then again, keeping it simple is the point!)
• More features are being daily
• Templates are being created

Your Turn

Have a look at R Markdown presentations and templates.

Pro tip: run devtools::install_github("rstudio/rticles") to get more templates

Yaml Front Matter

The stuff at the top of the .Rmd file (called yaml front matter) tells rmarkdown what output format you want.

---
title: "Untitled"
date: "May 16, 2016"
output: html_document
---

In this case, when you click “Knit HTML”, RStudio calls rmarkdown::render("file.Rmd", html_document()). You can certainly change these default values (see the source of this presentation).

What is a code chunk?

A code chunk is a concept borrowed from the knitr package (which, in turn, was inspired by literate programming). In .Rmd files, you can start/end a code chunk with three back-ticks.

1 + 1
## [1] 2

Want to run a command in another language?

print "a" + "b"
## ab

Code chunk options

There are a plethora of chunk options in knitr (engine is one of them). Here are some that I typically use:

• echo: Show the code?
• eval: Run the code?
• message: Relay messages?
• warning: Relay warnings?
• fig.width and fig.height: Change size of figure output.
• cache: Save the output of this chunk (so we don’t have to run it next time)?

Formatting R output

m <- lm(mpg ~ disp, data = mtcars)
summary(m) # output isn't very attractive
## 
## Call:
## lm(formula = mpg ~ disp, data = mtcars)
## 
## Residuals:
##     Min      1Q  Median      3Q     Max 
## -4.8922 -2.2022 -0.9631  1.6272  7.2305 
## 
## Coefficients:
##              Estimate Std. Error t value Pr(>|t|)    
## (Intercept) 29.599855   1.229720  24.070  < 2e-16 ***
## disp        -0.041215   0.004712  -8.747 9.38e-10 ***
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
## 
## Residual standard error: 3.251 on 30 degrees of freedom
## Multiple R-squared:  0.7183, Adjusted R-squared:  0.709 
## F-statistic: 76.51 on 1 and 30 DF,  p-value: 9.38e-10

pander is one great option.

library(pander)
pander(m)

Pander knows about a lot of stuff!

methods(pander)
##  [1] pander.anova*           pander.aov*            
##  [3] pander.aovlist*         pander.call*           
##  [5] pander.cast_df*         pander.character*      
##  [7] pander.clogit*          pander.coxph*          
##  [9] pander.CrossTable*      pander.data.frame*     
## [11] pander.Date*            pander.default*        
## [13] pander.density*         pander.describe*       
## [15] pander.evals*           pander.factor*         
## [17] pander.formula*         pander.ftable*         
## [19] pander.function*        pander.glm*            
## [21] pander.htest*           pander.image*          
## [23] pander.list*            pander.lm*             
## [25] pander.lme*             pander.logical*        
## [27] pander.matrix*          pander.microbenchmark* 
## [29] pander.mtable*          pander.NULL*           
## [31] pander.numeric*         pander.option          
## [33] pander.POSIXct*         pander.POSIXlt*        
## [35] pander.prcomp*          pander.rapport*        
## [37] pander.return           pander.rlm*            
## [39] pander.sessionInfo*     pander.smooth.spline*  
## [41] pander.stat.table*      pander.summary.aov*    
## [43] pander.summary.aovlist* pander.summary.glm*    
## [45] pander.summary.lm*      pander.summary.prcomp* 
## [47] pander.survdiff*        pander.survfit*        
## [49] pander.table*           pander.tabular*        
## [51] pander.ts*              pander.zoo*            
## see '?methods' for accessing help and source code

Your Turn

• Look through the list of pander methods. Can you apply any of the methods that we haven’t discussed? We just saw pander.lm and pander.anova.